Backwash is a printing extension which allows you to specify a QuickDraw PICT to use as a background for the pages of a printed document.
-- Technical overview --
At GXJobPrintDialog time, the extension installs a panel in the print dialog which allows you to select a QuickDraw PICT file. Later, at GXCreateSpoolFile time, the PICT file is read in, translated to a QuickDraw GX shape, flattened, and added to the spool file as a resource. At GXDespoolPage time, the flattened shape is read back in, unflattened and added as a background to the printed page.
-- Print panel features --
The “intensity” item in the print panel allows you to specify how "vivid" the background image should appear. If background pictures are added at full intensity, they tend to wash out any text or drawing that's printed on top of them. Normally, you want to add the image at 50% intensity or less. 100% causes the shape to be added at original intensity, 50% makes it appear half as dark, and 0% causes the shape to be pure white.
The "Application prints with TextEdit" checkbox provides a way to make the printing extension work with applications which print using TextEdit. When TextEdit draws, the area being drawn to is first erased. As this goes through the QuickDraw to QuickDraw GX translator during printing, these erasures are interpreted as white rectangles, which are added to the page shape. The result is that text appears with white rectangles drawn behind it, and those white rectangles obscure any background image.
To work around this, the extension allows you to specify that an application prints text with TextEdit. If you indicate this, the page shape is stripped of any white rectangles during printing. This is not a perfect solution. There are situations (for example in graphics applications) where you actually may want white rectangles on the page. Also, this method will not work with non-GX applications due to changes in the way shapes are spooled since 1.0b3. For now, the best approach is to print without the "uses TextEdit" option set unless you have problems. I'll work on a more accurate solution for a future version.
This extension shows a number of things:
• How to write an extension which installs a panel, handles panel events and uses the way-cool ‘xdtl’ resources.
• How to handle some items in print panels independently of 'xdtls'.
• How to translate QuickDraw PICTs to GX shapes.
• How to flatten and unflatten shapes using handles.
• How to add and retrieve spool file resources.
• How to use global data in a printing extension.
-- Design changes --
This printing extension has been updated significantly since the 1.0a5 seed, where it first appeared. The original printing extension had memory problems, wouldn't work if the spool file were dragged from one machine to another, and so forth. This version corrects those problems, but still isn't as efficient as it could be. More on that below.
The picture is now added to the spool file, so that if the original image is deleted, the extension can still function. In adding the picture to the spool file, there were four options I came up with.
* option #1 - Add the background shape to each page during spooling.
This could make for some pretty huge spool files, so I threw this idea out.
* option #2 - Add the shape as a format form to each unique format during spooling.
I abandoned this approach partly because I couldn't get it working very well, and partly because you might still save multiple copies of the background shape in the spool file. If you have a document with 4 unique page formats, for example, the background shape would be added 4 times. With large pictures, that can increase your spool file size pretty fast.
* option #3 - Add the shape once, as a collection item during spooling.
"The Collection Manager is not a database." If PrinterShare tries to load the collection item into its heap during despooling and can't, the extension would fail. PrinterShare's heap is relatively small, so this approach is likely to fail with most PICTs.
* option #4 - Add the shape once, as a spool file resource during spooling.
This is what I ended up doing. Because this approach has the same PrinterShare memory problem that the previous method has, I set the resource to load into the system heap. This works great, and results in the picture only being written to the spool file once.
Ideally, the extension would simply add the Backwash picture to each unique format during despooling. Currently, the shape is added to each page shape being despooled. The advantage of using forms is that the background image can be sent to the printer once for several pages, so subsequent pages print much faster. And, unlike the current implementation, the background image will appear behind the graphics in the format's form, if there is one. Pictures added with the current version of Backwash will appear on top of any form that's being used.
